📄 Builds

To ensure a seamless experience for all contributors, it is essential to run Docusaurus builds (pnpm build) frequently. Because Docusaurus enforces strict formatting and syntax rules, local builds act as a safeguard, catching errors before they reach the shared repository.

Pushing to or committing directly to main

Please check with the product owner with regards to direct changes to the main branch.

Why Frequent Builds Matter

• Prevent Blocker Issues: Markdown errors in one file can stall the build process for the entire team, preventing others from successfully committing or deploying their changes.

• Standardize Legacy Content: The legacy tasks repository contains a high volume of less than optimum formatted Markdown. Migrating this content into Docusaurus requires diligent cleanup to meet modern documentation standards.

• Validate Formatting: Docusaurus will explicitly fail if it encounters "ill-prepared" content. Regular testing ensures your contributions are always "production-ready."

• The Bottom Line: The transition from a "hodgepodge" of files to an organized system requires a shift toward diligent authoring. The payoff is a cleaner, more searchable, and professional knowledge base for everyone.

Local Builds

There is a Husky pre-push hook as part of the content editor experience. Whether you push to main or another branch the Docusaurus build will run. Consider the following push commands:

pnpm build

git push

git push --dry-run

git push --no-verify

pnpm build

While the current Docusaurus configuration is set to only issue warnings for broken internal links and missing image sources, running a local build remains a critical preventative step. Executing this check manually will not only catch React compile issues but also allows you to identify and resolve pathing issues before they are committed to the remote repository.

git push

It is generally safe to run this command as the Docusaurus build command will stop the remote push if it cannot build the web site. However it currently only gives warnings for broken links and image src URLs. Consider running pnpm build first to fix broken links and image URLs.

git push --dry-run

The git push --dry-run command allows you to simulate a push to a remote repository without actually uploading any data or updating your remote branches. This is a good test to view the outcome of the push command.

git push --no-verify

Using git push --no-verify allows a developer to bypass the pre-push hooks—automated safeguards like linters and tests—designed to protect the repository's integrity. While an emergency might seem to justify skipping these checks, doing so merely shifts the burden of unresolved build errors from the local environment to the remote repository.

This practice often forces colleagues to inherit and fix broken code, disrupting the collective workflow and potentially stalling the CI/CD pipeline. Ultimately, bypassing hooks is a significant judgment call that risks trading short-term speed for long-term technical debt and team friction. A better approach is to address the underlying errors locally, ensuring that every contribution strengthens rather than destabilizes the codebase.

Workflow Action: Test Build

This workflow will run when you create a pull request. Please wait for it to finish before merging the pull request.

name: Test Build

on:
  workflow_dispatch:
  pull_request:
    branches:
      - main
...

Workflow Action: Build and Deploy

This workflow will run when there is a push to the main branch. It will run a build and update the Docusaurus website.

name: Build & Deploy (gh-pages)

on:
  workflow_dispatch:
  push:
    branches:
      - main
...

---

Owner: Warren